---
title: CLI 命令
---

import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

你可以使用 Astro 提供的命令行界面 (CLI) 从终端窗口开发、构建和预览你的项目。

### `astro` 命令

通过使用你喜欢的包管理器运行此页面上记录的**命令**之一来使用 CLI，可选择后跟任何**标志**。标志可以自定义命令的行为。

你最常使用的命令之一是 `astro dev`。这个命令启动开发服务器，并在浏览器中为你提供一个实时更新的网站预览，以便你在工作时查看。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 启动开发服务器
  npx astro dev
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 启动开发服务器
  pnpm astro dev
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 启动开发服务器
  yarn astro dev
  ```
  </Fragment>
</PackageManagerTabs>

你可以在终端中输入 `astro --help` 来显示所有可用命令的列表：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro --help
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro --help
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro --help
  ```
  </Fragment>
</PackageManagerTabs>

下面的消息将在你的终端中显示：

```bash
astro [command] [...flags]

Commands
              add  Add an integration.
            build  Build your project and write it to disk.
            check  Check your project for errors.
        create-key Create a cryptography key
              dev  Start the development server.
             docs  Open documentation in your web browser.
             info  List info about your current Astro setup.
          preview  Preview your build locally.
             sync  Generate TypeScript types for all Astro modules.
      preferences  Configure user preferences.
        telemetry  Configure telemetry settings.

Global Flags
  --config <path>  Specify your config file.
    --root <path>  Specify your project root folder.
     --site <url>  Specify your project site.
--base <pathname>  Specify your project base.
        --verbose  Enable verbose logging.
         --silent  Disable all logging.
        --version  Show the version number and exit.
           --help  Show this help message.
```

你可以在任何命令后添加 `--help` 标志，以获取该命令的所有标志的列表。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 获取 `dev` 命令的所有标志的列表
  npm run dev -- --help
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 获取 `dev` 命令的所有标志的列表
  pnpm dev --help
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 获取 `dev` 命令的所有标志的列表
  yarn dev --help
  ```
  </Fragment>
</PackageManagerTabs>

下面的消息将在你的终端中显示：

```bash
astro dev [...flags]

Flags
                 --port  Specify which port to run on. Defaults to 4321.
                 --host  Listen on all addresses, including LAN and public addresses.
--host <custom-address>  Expose on a network IP address at <custom-address>
                 --open  Automatically open the app in the browser on server start
                --force  Clear the content layer cache, forcing a full rebuild.
            --help (-h)  See all available flags.
```

:::note
你需要在标志前添加 `--` 才能让 `npm` 把这些标志传递给 `astro` 命令。
:::

### `package.json` 脚本

你也可以在 `package.json` 中使用脚本来使用这些命令的简短版本。使用脚本允许你使用来自其他项目的相同命令，例如 `npm run build`。

当你使用 [`create astro` 向导](/zh-cn/install-and-setup/) 创建项目时，以下脚本是为你自动添加的，用于最常用的 `astro` 命令（`astro dev`、`astro build` 和 `astro preview`）。

当你按照[手动安装 Astro](/zh-cn/install-and-setup/#手动安装) 的说明进行操作时，你会被告知自己添加这些脚本。你还可以手动为任何你经常使用的命令添加更多脚本到这个列表中。

```json title="package.json"
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}
```

你经常会使用这些 `astro` 命令，或者运行它们的脚本，而不带任何标志。当你想要自定义命令的行为时，可以向命令添加标志。例如，你可能希望在不同的端口上启动开发服务器，或者使用详细日志构建站点以进行调试。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 使用 `package.json` 中的 `dev` 脚本，以端口 8080 启动开发服务器
  npm run dev -- --port 8080

  # 使用 `package.json` 中的 `build` 脚本，构建带有详细日志的网站
  npm run build -- --verbose
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 使用 `package.json` 中的 `dev` 脚本，以端口 8080 启动开发服务器
  pnpm dev --port 8080

  # 使用 `package.json` 中的 `build` 脚本，构建带有详细日志的网站
  pnpm build --verbose
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 使用 `package.json` 中的 `dev` 脚本，以端口 8080 启动开发服务器
  yarn dev --port 8080

  # 使用 `package.json` 中的 `build` 脚本，构建带有详细日志的网站
  yarn build --verbose
  ```
  </Fragment>
</PackageManagerTabs>

## `astro dev`

运行 Astro 的开发服务器。这是一个不打包资源的本地 HTTP 服务器。当你在编辑器中保存更改时，它使用热模块替换 (HMR) 来更新你的浏览器。

你可以在终端，也就是 Astro 开发服务器所运行的位置，使用以下的快捷键：

- `s + enter` 用以同步内容层（content layer）的数据（内容与类型）。
- `o + enter` 用以在浏览器中打开你的 Astro 网站。
- `q + enter` 用以退出开发服务器。

## `astro build`

构建你的网站以进行部署。默认情况下，这将生成静态文件并将它们放在 `dist/` 目录中。如果有任何路由是[按需渲染](/zh-cn/guides/on-demand-rendering/)的，这将生成必要的服务器文件为你的网站提供服务。

<h3>标志</h3>

该命令接受 [通用标志](#通用标志) 和以下额外标志：

#### `--devOutput`

<p><Since v="5.0.0" /></p>

输出基于开发的构建，类似于在 `astro dev` 中转换的代码。这对于测试仅在构建时出现的问题并包含额外的调试信息非常有用。


## `astro preview`

启动一个本地服务器，用于提供由运行 `astro build` 创建的静态目录（默认为 `dist/`）的内容。

该命令允许你在部署之前[构建](#astro-build)本地预览你的网站，以便在构建输出中捕获任何错误。它不是为在生产环境中运行而设计的。有关生产托管的帮助，请查看我们的[部署 Astro 网站](/zh-cn/guides/deploy/)指南。

在运行 Astro 预览服务器的终端中，可以使用以下快捷键：
- `o` + `enter` 在浏览器中打开 Astro 网站。
- `q` + `enter` 退出预览服务器。

`astro preview` 命令可以和下面文档的 [通用标志](#通用标志) 结合使用，以进一步控制预览体验。

## `astro check`

对项目进行检测（比如对 `.astro` 文件进行类型检查），并向控制台输出错误信息。如果发现任何错误，该进程将以 **1** 代码退出。

该命令旨在用于 CI 工作流程。

<h3>标志</h3>

使用这些标志来自定义命令的行为。

#### `--watch`

该命令将监听你项目中的任何更改，并报告任何错误。

#### `--root <path-to-dir>`

指定一个不同的根目录进行检查。默认使用当前工作目录。

#### `--tsconfig <path-to-file>`

指定手动使用的 `tsconfig.json` 文件。如果未提供，Astro 将尝试找到配置，或自动推断项目的配置。

#### `--minimumFailingSeverity <error|warning|hint>`

指定退出并返回错误代码所需的最低严重性级别。默认为 `error`。

例如，运行 `astro check --minimumFailingSeverity warning` 会在检测到任何警告时使命令退出并报错。

#### `--minimumSeverity <error|warning|hint>`

指定要输出的最低严重性级别。默认为 `hint`。

例如，运行 `astro check --minimumSeverity warning` 将显示错误和警告，但不显示提示。

#### `--preserveWatchOutput`

指定在监听模式下，不清除检查之间的输出。

#### `--noSync`

指定在检查项目之前，不运行 `astro sync`。

<ReadMore>阅读更多关于 [在 Astro 中类型检查](/zh-cn/guides/typescript/) 的信息。</ReadMore>

## `astro sync`

<p><Since v="2.0.0" /></p>

:::tip
运行 `astro dev`，`astro build`或者`astro check`也会运行`sync`命令。
:::

为所有 Astro 模块生成 TypeScript 类型。这会为类型推断设置一个[`.astro/types.d.ts`文件](/zh-cn/guides/typescript/#设置)，并为依赖于生成类型的特性定义模块：

- `astro:content` 模块用于 [内容集合 API](/zh-cn/guides/content-collections/)。
- `astro:db` 模块用于 [Astro DB](/zh-cn/guides/astro-db/)。
- `astro:env` 模块用于 [Astro Env](/zh-cn/guides/environment-variables/)。
- `astro:actions` 模块用于 [Astro Actions](/zh-cn/guides/actions/)。

## `astro add`

将集成添加到你的配置中。在[集成指南](/zh-cn/guides/integrations-guide/#自动集成设置)中阅读更多信息。

## `astro docs`

直接从终端启动 Astro Docs 网站。

## `astro info`

显示当前 Astro 环境的有用信息，以便在提交 issue 时提供信息。

```shell
astro info
```

输出示例：

```
Astro                    v5.14.1
Vite                     v6.3.6
Node                     v22.17.1
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             @astrojs/starlight (v0.35.3)
```

<h3>标志</h3>

使用以下标志来定制命令的行为。

#### `--copy`

该命令会将输出复制到剪贴板，而不会发出提示。

## `astro preferences`

使用 `astro preferences` 命令管理用户偏好。用户偏好是特定于单个 Astro 用户的，不像 `astro.config.mjs` 文件，它会改变所有项目的所有人的行为。

默认情况下，用户偏好是针对当前项目的，存储在本地的 `.astro/settings.json` 文件中。

使用 `--global` 标志，用户偏好也可以应用于当前机器上的每个 Astro 项目。全局用户偏好存储在特定于操作系统的位置。

<h3> 可配置的偏好设置 </h3>

- `devToolbar` — 在浏览器中启用或禁用开发工具栏。（默认值：`true`）
- `checkUpdates` — 启用或禁用 Astro CLI 的自动更新检查。（默认值：`true`）

`list` 命令打印所有可配置用户偏好的当前设置。它还支持机器可读的 `--json` 输出格式。

```shell
astro preferences list
```

终端输出示例：

| Preference               | Value |
| ------------------------ | ----- |
| devToolbar.enabled       | true  <tr></tr>|
| checkUpdates.enabled     | true  |

你可以通过 `enable`、`disable` 或 `reset` 命令来启用、禁用或重置偏好设置至默认值。

举个例子，要在特定的 Astro 项目中禁用 devToolbar：

```shell
astro preferences disable devToolbar
```

要在当前机器上的所有 Astro 项目中禁用 devToolbar：

```shell
astro preferences disable --global devToolbar
```

稍后可以使用以下命令启用 devToolbar：

```shell
astro preferences enable devToolbar
```

`reset` 命令将偏好重置为其默认值：

```shell
astro preferences reset devToolbar
```

## `astro telemetry`

为当前 CLI 用户设置遥测配置。遥测是匿名数据，可让 Astro 团队深入了解最常使用哪些 Astro 功能。有关更多信息，请参阅 [Astro 的遥测页面](https://astro.build/telemetry/)。

可以通过这个 CLI 命令禁用遥测：

```shell
astro telemetry disable
```

后面也可以随时通过以下方式重新启用遥测：

```shell
astro telemetry enable
```

使用 `reset` 命令重置遥测数据：

```shell
astro telemetry reset
```

:::tip[想要在 CI 环境中禁用遥测？]
将 `astro telemetry disable` 命令添加到你的 CI 脚本或设置 `ASTRO_TELEMETRY_DISABLED` 环境变量。
:::

## `astro create-key`

生成一个密钥，用于加密传递给服务器群岛的属性。

```shell
astro create-key
```

将此密钥设置为 `ASTRO_KEY` 环境变量（例如在 `.env` 文件中），并在需要 [为服务器群岛提供常量加密密钥](/zh-cn/guides/server-islands/#复用加密密钥) 时，将其包含在 CI/CD 或主机的构建设置中，例如滚动部署、多区域托管或缓存包含服务器群岛的页面的 CDN。


## 通用标志

### `--root <path>`

指定项目根目录的路径。如果不指定，则假定当前工作目录为根目录。

根目录是用来寻找 Astro 配置文件的。

```shell
astro --root myRootFolder/myProjectFolder dev
```

### `--config <path>`

指定配置文件的路径。默认为 `astro.config.mjs`。如果使用了不同的配置文件名称或放在其他文件夹中，请使用：

```shell
astro --config config/astro.config.mjs dev
```

### `--force <string>`

<p><Since v="5.0.0" /></p>

清除 [content layer 缓存](/zh-cn/guides/content-collections/#定义集合-loader)，强制重新编译。

### `--mode <string>`

<p><Since v="5.0.0" /></p>

为你的项目配置 [`mode`](/zh-cn/reference/programmatic-reference/#mode) 行内配置。

### `--outDir <path>`

<p><Since v="3.3.0" /></p>

为你的项目配置 [`outDir`](/zh-cn/reference/configuration-reference/#outdir)。传递此标志将覆盖 `astro.config.mjs` 文件中的 `outDir` 值（如果存在）。

### `--site  <url>`

为你的项目配置 [`site`](/zh-cn/reference/configuration-reference/#base)。传递此标志将覆盖 `astro.config.mjs` 文件中的 `site` 值（如果存在）。

### `--base <pathname>`

<p><Since v="1.4.1" /></p>

为你的项目配置 [`base`](/zh-cn/reference/configuration-reference/#base)。传递此标志将覆盖 `astro.config.mjs` 文件中的 `base` 值（如果存在）。

### `--port <number>`

指定运行开发服务器和预览服务器的端口。默认为 `4321`。

### `--host [optional host address]`

设置开发服务器和预览服务器应监听的网络 IP 地址（即非 localhost IP）。这在开发过程中对于在本地设备（如手机）上测试你的项目非常有用。

- `--host` — 在所有地址上监听，包括 LAN 和公共地址
- `--host <custom-address>` — 在 `<custom-address>` 的网络 IP 地址上公开

:::caution
不要在生产环境中使用 `--host` 标志来公开开发服务器和预览服务器。这些服务器仅设计用于在开发你的网站时本地使用。
:::

### `--allowed-hosts`

<p><Since v="5.4.0" /></p>

在 `dev` 或 `preview` 模式下，指定允许 Astro 响应的主机名（hostname）。可以传入一列由逗号分割的主机名来进行许可，或者是传入 `true` 来对任何的主机名都进行许可。

更多信息请参阅 [Vite 的 `allowedHosts` 功能](https://cn.vite.dev/config/server-options#server-allowedhosts)，其中包含了许可主机名的安全隐患。

### `--verbose`

启用完整日志，调试时有用。

### `--silent`

启用静默日志，当你不想看到 Astro 日志时有用。

### `--open`

在服务器启动时自动在浏览器中打开应用程序。可以传递完整的 URL 字符串 (例如 `--open http://example.com`) 或路径名 (例如 `--open /about`) 来指定要打开的 URL。

## 全局标志

使用这些标志获取有关 `astro` CLI 的信息。

### `--version`

打印 Astro 版本号并退出。

### `--help`

打印帮助信息并退出。
